Language/OS - Multiplatform Resource Library

home *** CD-ROM | disk | FTP | other *** search

/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / pcl / docs.lha / cmu-user / cmu-user.info-1 < prev next >

Wrap

Text File | 1992-08-05 | 53KB | 1,639 lines

Info file: cmu-user.info, -*-Text-*- produced by latexinfo-format-buffer from file: cmu-user.tex File: cmu-user.info Node: Top, Prev: (dir), Up: (dir), Next: Introduction CMU Common Lisp User's Manual Robert A. MacLachlan, EDITOR School of Computer Science Carnegie Mellon University Pittsburgh, PA 15213 * Menu: * Introduction:: * Design Choices and Extensions:: * The Debugger:: * The Compiler:: * Advanced Compiler Use and Efficiency Hints:: * UNIX Interface:: * Event Dispatching with SERVE-EVENT:: * Alien Objects:: * Interprocess Communication under LISP:: * Debugger Programmer's Interface:: * Function Index:: * Variable Index:: * Type Index:: * Concept Index:: --- The Detailed Node Listing --- Introduction * Support:: * Local Distribution of CMU Common Lisp:: * Net Distribution of CMU Common Lisp:: * Source Availability:: * Command Line Options:: * Credits:: Design Choices and Extensions * Data Types:: * Default Interrupts for Lisp:: * Packages:: * The Editor:: * Garbage Collection:: * Describe:: * The Inspector:: * Load:: * The Reader:: * Running Programs from Lisp:: * Saving a Core Image:: * Search Lists:: * Time Parsing and Formatting:: * Lisp Library:: Data Types * Symbols:: * Integers:: * Floats:: * Characters:: * Array Initialization:: Floats * IEEE Special Values:: * Negative Zero:: * Denormalized Floats:: * Floating Point Exceptions:: * Floating Point Rounding Mode:: * Accessing the Floating Point Modes:: The Inspector * The Windowing Inspector:: * The TTY Inspector:: Running Programs from Lisp * Process Accessors:: Search Lists * Search List Example:: The Debugger * Debugger Introduction:: * The Command Loop:: * Stack Frames:: * Variable Access:: * Source Location Printing:: * Compiler Policy Control:: * Exiting Commands:: * Information Commands:: * Breakpoint Commands:: * Function Tracing:: * Specials:: Stack Frames * Stack Motion:: * How Arguments are Printed:: * Function Names:: * Funny Frames:: * Debug Tail Recursion:: * Unknown Locations and Interrupts:: Variable Access * Variable Value Availability:: * Note On Lexical Variable Access:: Source Location Printing * How the Source is Found:: * Source Location Availability:: Breakpoint Commands * Breakpoint Example:: Function Tracing * Encapsulation Functions:: The Compiler * Compiler Introduction:: * Calling the Compiler:: * Compilation Units:: * Interpreting Error Messages:: * Types in Python:: * Getting Existing Programs to Run:: * Compiler Policy:: * Open Coding and Inline Expansion:: Compilation Units * Undefined Warnings:: * Context Declarations:: * Context Declaration Example:: Interpreting Error Messages * The Parts of the Error Message:: * The Original and Actual Source:: * The Processing Path:: * Error Severity:: * Errors During Macroexpansion:: * Read Errors:: * Error Message Parameterization:: Types in Python * Compile Time Type Errors:: * Precise Type Checking:: * Weakened Type Checking:: Compiler Policy * The Optimize Declaration:: * The Optimize-Interface Declaration:: Advanced Compiler Use and Efficiency Hints * Advanced Compiler Introduction:: * More About Types in Python:: * Type Inference:: * Source Optimization:: * Tail Recursion:: * Local Call:: * Block Compilation:: * Inline Expansion:: * Object Representation:: * Numbers:: * General Efficiency Hints:: * Efficiency Notes:: * Profiling:: Advanced Compiler Introduction * Types:: * Optimization:: * Function Call:: * Representation of Objects:: * Writing Efficient Code:: More About Types in Python * More Types Meaningful:: * Canonicalization:: * Member Types:: * Union Types:: * The Empty Type:: * Function Types:: * The Values Declaration:: * Structure Types:: * The Freeze-Type Declaration:: * Type Restrictions:: * Type Style Recommendations:: Type Inference * Variable Type Inference:: * Local Function Type Inference:: * Global Function Type Inference:: * Operation Specific Type Inference:: * Dynamic Type Inference:: * Type Check Optimization:: Source Optimization * Let Optimization:: * Constant Folding:: * Unused Expression Elimination:: * Control Optimization:: * Unreachable Code Deletion:: * Multiple Values Optimization:: * Source to Source Transformation:: * Style Recommendations:: Tail Recursion * Tail Recursion Exceptions:: Local Call * Self-Recursive Calls:: * Let Calls:: * Closures:: * Local Tail Recursion:: * Return Values:: Block Compilation * Block Compilation Semantics:: * Block Compilation Declarations:: * Compiler Arguments:: * Practical Difficulties:: Inline Expansion * Inline Expansion Recording:: * Semi-Inline Expansion:: * The Maybe-Inline Declaration:: Object Representation * Think Before You Use a List:: * Structures:: * Arrays:: * Vectors:: * Bit-Vectors:: * Hashtables:: Numbers * Descriptors:: * Non-Descriptor Representations:: * Variables:: * Generic Arithmetic:: * Fixnums:: * Word Integers:: * Floating Point Efficiency:: * Specialized Arrays:: * Interactions With Local Call:: * Representation of Characters:: General Efficiency Hints * Compile Your Code:: * Avoid Unnecessary Consing:: * Complex Argument Syntax:: * Mapping and Iteration:: * Trace Files and Disassembly:: Efficiency Notes * Type Uncertainty:: * Efficiency Notes and Type Checking:: * Representation Efficiency Notes:: * Verbosity Control:: Profiling * Profile Interface:: * Profiling Techniques:: * Nested or Recursive Calls:: * Clock resolution:: * Profiling overhead:: * Additional Timing Utilities:: * A Note on Timing:: * Benchmarking Techniques:: UNIX Interface * Reading the Command Line:: * Lisp Equivalents for C Routines:: * Type Translations:: * System Area Pointers:: * Unix System Calls:: * File Descriptor Streams:: * Making Sense of Mach Return Codes:: * Unix Interrupts:: Unix Interrupts * Changing Interrupt Handlers:: * Examples of Signal Handlers:: Event Dispatching with SERVE-EVENT * Object Sets:: * The SERVE-EVENT Function:: * Using SERVE-EVENT with Unix File Descriptors:: * Using SERVE-EVENT with the CLX Interface to X:: * A SERVE-EVENT Example:: Using SERVE-EVENT with the CLX Interface to X * Without Object Sets:: * With Object Sets:: A SERVE-EVENT Example * Without Object Sets Example:: * With Object Sets Example:: Alien Objects * Introduction to Aliens:: * Alien Types:: * Alien Operations:: * Alien Variables:: * Alien Data Structure Example:: * Loading Unix Object Files:: * Alien Function Calls:: * Step-by-Step Alien Example:: Alien Types * Defining Alien Types:: * Alien Types and Lisp Types:: * Alien Type Specifiers:: * The C-Call Package:: Alien Operations * Alien Access Operations:: * Alien Coercion Operations:: * Alien Dynamic Allocation:: Alien Variables * Local Alien Variables:: * External Alien Variables:: Alien Function Calls * alien-funcall:: The alien-funcall Primitive * def-alien-routine:: The def-alien-routine Macro * def-alien-routine Example:: * Calling Lisp from C:: Interprocess Communication under LISP * The REMOTE Package:: * The WIRE Package:: * Out-Of-Band Data:: The REMOTE Package * Connecting Servers and Clients:: * Remote Evaluations:: * Remote Objects:: * Host Addresses:: The WIRE Package * Untagged Data:: * Tagged Data:: * Making Your Own Wires:: Debugger Programmer's Interface * DI Exceptional Conditions:: * Debug-variables:: * Frames:: * Debug-functions:: * Debug-blocks:: * Breakpoints:: * Code-locations:: * Debug-sources:: * Source Translation Utilities:: DI Exceptional Conditions * Debug-conditions:: * Debug-errors:: File: cmu-user.info Node: Introduction, Prev: Top, Up: Top, Next: Design Choices and Extensions Introduction ************ CMU Common Lisp is a public-domain implementation of Common Lisp developed in the Computer Science Department of Carnegie Mellon University. CMU Common Lisp is currently supported on MIPS-processor DECstations, Sparc-based workstations from Sun and the IBM RT PC, and other ports are planned. Currently, it runs under CMU's Mach operating system, OSF/1 or SunOS. This document describes the implementation based on the Python compiler. Previous versions of CMU Common Lisp ran on the IBM RT PC and (when known as Spice Lisp) on the Perq workstation. See `man cmucl' (`man/man1/cmucl.1') for other general information. CMU Common Lisp sources and executables are freely available via anonymous FTP; this software is "as is", and has no warranty of any kind. CMU and the authors assume no responsibility for the consequences of any use of this software. See `doc/release-notes.txt' for a description of the state of the release you have. * Menu: * Support:: * Local Distribution of CMU Common Lisp:: * Net Distribution of CMU Common Lisp:: * Source Availability:: * Command Line Options:: * Credits:: File: cmu-user.info Node: Support, Prev: Introduction, Up: Introduction, Next: Local Distribution of CMU Common Lisp Support ======= The CMU Common Lisp project's goal is to develop a high quality public domain system, so we want your bug reports, bug fixes and enhancements. However, staff limitations prevent us from providing extensive support to people outside of CMU. We are looking for university and industrial affiliates to help us with porting and maintenance for hardware and software that is not widely used at CMU. This manual contains only implementation-specific information about CMU Common Lisp. Users will also need a separate manual describing the CMU Common Lisp standard. CMU Common Lisp was initially defined in Common Lisp: The Language, by Guy L. Steele Jr. CMU Common Lisp is now undergoing standardization by the X3J13 committee of ANSI. The X3J13 spec is not yet completed, but a number of clarifications and modification have been approved. We intend that CMU Common Lisp will eventually adhere to the X3J13 spec, and we have already implemented many of the changes approved by X3J13. Until the X3J13 standard is completed, the second edition of is probably the best available manual for the language and for our implementation of it. This book has no official role in the standardization process, but it does include many of the changes adopted since the first edition was completed. In addition to the language itself, this document describes a number of useful library modules that run in CMU Common Lisp. hemlock, an Emacs-like text editor, is included as an integral part of the CMU Common Lisp environment. Two documents describe hemlock: the Hemlock User's Manual, and the Hemlock Command Implementor's Manual. File: cmu-user.info Node: Local Distribution of CMU Common Lisp, Prev: Support, Up: Introduction, Next: Net Distribution of CMU Common Lisp Local Distribution of CMU Common Lisp ===================================== At CMU, you can get Common Lisp by running `modmisc': /usr/cs/etc/modmisc - cs.misc.cmucl This establishes `/usr/misc/.cmucl' as a symbolic link to the release area. In your `.login', add CMU CL to your path: setpath -i /usr/misc/.cmucl Then run `lisp'. Note that the first time you run Lisp, it will take AFS several minutes to copy the image into its local cache. Subsequent starts will be much faster. Or, you can run directly out of the AFS release area (which may be necessary on SunOS machines). Put this in your `.login' shell script: setenv CMUCLLIB "/afs/cs/misc/cmucl/@sys/beta/lib" setpath -i /afs/cs/misc/cmucl/@sys/beta After setting your path, ``man cmucl'' will give an introduction to CMU CL and `man lisp' will describe command line options. For SunOS installation notes, see the `README' file in the SunOS release area. See `/usr/misc/.cmucl/doc' for release notes and documentation. Hardcopy documentation is available in the document room. Documentation supplements may be available for recent additions: see the `README' file. Send bug reports and questions to `cmucl-bugs@cs.cmu.edu'. If you send a bug report to `gripe' or `help', they will just forward it to this mailing list. File: cmu-user.info Node: Net Distribution of CMU Common Lisp, Prev: Local Distribution of CMU Common Lisp, Up: Introduction, Next: Source Availability Net Distribution of CMU Common Lisp =================================== Externally, CMU Common Lisp is only available via anonymous FTP. We don't have the manpower to make tapes. These are our distribution machines: lisp-rt1.slisp.cs.cmu.edu (128.2.217.9) lisp-rt2.slisp.cs.cmu.edu (128.2.217.10) Log in with the user `anonymous' and `username@host' as password (i.e. your EMAIL address.) When you log in, the current directory should be set to the CMU Common Lisp release area. If you have any trouble with FTP access, please send mail to `slisp@cs.cmu.edu'. The release area holds compressed tar files with names of the form: VERSION-MACHINE_OS.tar.Z FTP compressed tar archives in binary mode. To extract, `cd' to the directory that is to be the root of the tree, then type: uncompress <file.tar.Z | tar xf - . The resulting tree is about 23 megabytes. For installation directions, see the section "site initialization" in README file at the root of the tree. If poor network connections make it difficult to transfer a 10 meg file, the release is also available split into five parts, with the suffix `.0' to `.4'. To extract from multiple files, use: cat file.tar.Z.* | uncompress | tar xf - . The release area also contains source distributions and other binary distributions. A listing of the current contents of the release area is in `FILES'. Major release announcements will be made to `comp.lang.lisp' until there is enough volume to warrant a `comp.lang.lisp.cmu'. File: cmu-user.info Node: Source Availability, Prev: Net Distribution of CMU Common Lisp, Up: Introduction, Next: Command Line Options Source Availability =================== Lisp and documentation sources are available via anonymous FTP ftp to any CMU CS machine. All CMU written code is public domain, but CMU CL also makes use of two imported packages: PCL and CLX. Although these packages are copyrighted, they may be freely distributed without any licensing agreement or fee. See the `README' file in the binary distribution for up-to-date source pointers. The release area contains a source distribution, which is an image of all the `.lisp' source files used to build a particular system VERSION: VERSION-source.tar.Z (3.6 meg) All of our files (including the release area) are actually in the AFS file system. On the release machines, the FTP server's home is the release directory: `/afs/cs.cmu.edu/project/clisp/release'. The actual working source areas are in other subdirectories of `clisp', and you can directly "cd" to those directories if you know the name. Due to the way anonymous FTP access control is done, it is important to "cd" to the source directory with a single command, and then do a "get" operation. File: cmu-user.info Node: Command Line Options, Prev: Source Availability, Up: Introduction, Next: Credits Command Line Options ==================== The command line syntax and environment is described in the lisp(1) man page in the man/man1 directory of the distribution. See also cmucl(1). Currently Lisp accepts the following switches: `-core' requires an argument that should be the name of a core file. Rather than using the default core file (`/usr/misc/.lisp/lib/lisp.core'), the specified core file is loaded. `-edit' specifies to enter Hemlock. A file to edit may be specified by placing the name of the file between the program name (usually `lisp') and the first switch. `-eval' accepts one argument which should be a Lisp form to evaluate during the start up sequence. The value of the form will not be printed unless it is wrapped in a form that does output. `-hinit' accepts an argument that should be the name of the hemlock init file to load the first time the function ed is invoked. The default is to load `hemlock-init.OBJECT-TYPE', or if that does not exist, `hemlock-init.lisp' from the user's home directory. If the file is not in the user's home directory, the full path must be specified. `-init' accepts an argument that should be the name of an init file to load during the normal start up sequence. The default is to load `init.OBJECT-TYPE' or, if that does not exist, `init.lisp' from the user's home directory. If the file is not in the user's home directory, the full path must be specified. `-noinit' accepts no arguments and specifies that an init file should not be loaded during the normal start up sequence. Also, this switch suppresses the loading of a hemlock init file when Hemlock is started up with the `-edit' switch. `-load' accepts an argument which should be the name of a file to load into Lisp before entering Lisp's read-eval-print loop. `-slave' specifies that Lisp should start up as a slave Lisp and try to connect to an editor Lisp. The name of the editor to connect to must be specified -- to find the editor's name, use the hemlock "`Accept Slave Connections'" command. The name for the editor Lisp is of the form: MACHINE-NAME`:'SOCKET where MACHINE-NAME is the internet host name for the machine and SOCKET is the decimal number of the socket to connect to. For more details on the use of the `-edit' and `-slave' switches, see the Hemlock User's Manual. Arguments to the above switches can be specified in one of two ways: SWITCH`='VALUE or SWITCH<SPACE>VALUE. For example, to start up the saved core file mylisp.core use either of the following two commands: `lisp -core=mylisp.core lisp -core mylisp.core' File: cmu-user.info Node: Credits, Prev: Command Line Options, Up: Introduction Credits ======= Since 1981 many people have contributed to the development of CMU Common Lisp. The currently active members are: David Axmark Miles Bader Ted Dunning Scott Fahlman * (fearless leader) Mike Garland + Paul Gleichauf * Sean Hallgren + Simon Leinen William Lott * Robert A. Maclachlan * Tim Moore Many people are voluntarily working on improving CMU Common Lisp. "*" means a full-time CMU employee, and "+" means a part-time student employee. A partial listing of significant past contributors follows: Rick Busdiecker Bill Chiles * Chris Hoover + John Kolojejchick Todd Kaufmann + Dave McDonald * Skef Wholey * File: cmu-user.info Node: Design Choices and Extensions, Prev: Introduction, Up: Top, Next: The Debugger Design Choices and Extensions ***************************** Several design choices in Common Lisp are left to the individual implementation, and some essential parts of the programming environment are left undefined. This chapter discusses the most important design choices and extensions. * Menu: * Data Types:: * Default Interrupts for Lisp:: * Packages:: * The Editor:: * Garbage Collection:: * Describe:: * The Inspector:: * Load:: * The Reader:: * Running Programs from Lisp:: * Saving a Core Image:: * Search Lists:: * Time Parsing and Formatting:: * Lisp Library:: File: cmu-user.info Node: Data Types, Prev: Design Choices and Extensions, Up: Design Choices and Extensions, Next: Default Interrupts for Lisp Data Types ========== * Menu: * Symbols:: * Integers:: * Floats:: * Characters:: * Array Initialization:: File: cmu-user.info Node: Symbols, Prev: Data Types, Up: Data Types, Next: Integers Symbols ------- As in i{Common Lisp: The Language}, all symbols and package names are printed in lower case, as a user is likely to type them. Internally, they are normally stored upper case only. File: cmu-user.info Node: Integers, Prev: Symbols, Up: Data Types, Next: Floats Integers -------- The fixnum type is equivalent to `(signed-byte 30)'. Integers outside this range are represented as a bignum or a word integer (?.) Almost all integers that appear in programs can be represented as a `fixnum', so integer number consing is rare. File: cmu-user.info Node: Floats, Prev: Integers, Up: Data Types, Next: Characters Floats ------ CMU Common Lisp supports two floating point formats: single-float and double-float. These are implemented with IEEE single and double float arithmetic, respectively. `short-float' is a synonym for `single-float', and `long-float' is a synonym for `double-float'. The initial value of read-default-float-format is `single-float'. Both `single-float' and `double-float' are represented with a pointer descriptor, so float operations can cause number consing. Number consing is greatly reduced if programs are written to allow the use of non-descriptor representations (?.) * Menu: * IEEE Special Values:: * Negative Zero:: * Denormalized Floats:: * Floating Point Exceptions:: * Floating Point Rounding Mode:: * Accessing the Floating Point Modes:: File: cmu-user.info Node: IEEE Special Values, Prev: Floats, Up: Floats, Next: Negative Zero IEEE Special Values ................... CMU Common Lisp supports the IEEE infinity and NaN special values. These non-numeric values will only be generated when trapping is disabled for some floating point exception (?), so users of the default configuration need not concern themselves with special values. -- Constant: short-float-positive-infinity -- Constant: short-float-negative-infinity -- Constant: single-float-positive-infinity -- Constant: single-float-negative-infinity -- Constant: double-float-positive-infinity -- Constant: double-float-negative-infinity -- Constant: long-float-positive-infinity -- Constant: long-float-negative-infinity The values of these constants are the IEEE positive and negative infinity objects for each float format. -- Function: float-infinity-p This function returns true if X is an IEEE float infinity (of either sign.) X must be a float. -- Function: float-nan-p -- Function: float-trapping-nan-p `float-nan-p' returns true if X is an IEEE NaN (Not A Number) object. `float-trapping-nan-p' returns true only if X is a trapping NaN. With either function, X must be a float. File: cmu-user.info Node: Negative Zero, Prev: IEEE Special Values, Up: Floats, Next: Denormalized Floats Negative Zero ............. The IEEE float format provides for distinct positive and negative zeros. To test the sign on zero (or any other float), use the CMU Common Lisp float-sign function. Negative zero prints as `-0.0f0' or `-0.0d0'. File: cmu-user.info Node: Denormalized Floats, Prev: Negative Zero, Up: Floats, Next: Floating Point Exceptions Denormalized Floats ................... CMU Common Lisp supports IEEE denormalized floats. Denormalized floats provide a mechanism for gradual underflow. The CMU Common Lisp float-precision function returns the actual precision of a denormalized float, which will be less than float-digits. Note that in order to generate (or even print) denormalized floats, trapping must be disabled for the underflow exception (?.) The CMU Common Lisp `least-positive-'FORMAT-`float' constants are denormalized. -- Function: float-normalized-p This function returns true if X is a denormalized float. X must be a float. File: cmu-user.info Node: Floating Point Exceptions, Prev: Denormalized Floats, Up: Floats, Next: Floating Point Rounding Mode Floating Point Exceptions ......................... The IEEE floating point standard defines several exceptions that occur when the result of a floating point operation is unclear or undesirable. Exceptions can be ignored, in which case some default action is taken, such as returning a special value. When trapping is enabled for an exception, a error is signalled whenever that exception occurs. These are the possible floating point exceptions: :underflow This exception occurs when the result of an operation is too small to be represented as a normalized float in its format. If trapping is enabled, the floating-point-underflow condition is signalled. Otherwise, the operation results in a denormalized float or zero. :overflow This exception occurs when the result of an operation is too large to be represented as a float in its format. If trapping is enabled, the floating-point-overflow exception is signalled. Otherwise, the operation results in the appropriate infinity. :inexact This exception occurs when the result of a floating point operation is not exact, i.e. the result was rounded. If trapping is enabled, the `extensions:floating-point-inexact' condition is signalled. Otherwise, the rounded result is returned. :invalid This exception occurs when the result of an operation is ill-defined, such as `(/ 0.0 0.0)'. If trapping is enabled, the `extensions:floating-point-invalid' condition is signalled. Otherwise, a quiet NaN is returned. :divide-by-zero This exception occurs when a float is divided by zero. If trapping is enabled, the divide-by-zero condition is signalled. Otherwise, the appropriate infinity is returned. File: cmu-user.info Node: Floating Point Rounding Mode, Prev: Floating Point Exceptions, Up: Floats, Next: Accessing the Floating Point Modes Floating Point Rounding Mode ............................ IEEE floating point specifies four possible rounding modes: :nearest In this mode, the inexact results are rounded to the nearer of the two possible result values. If the neither possibility is nearer, then the even alternative is chosen. This form of rounding is also called "round to even", and is the form of rounding specified for the CMU Common Lisp round function. :positive-infinity This mode rounds inexact results to the possible value closer to positive infinity. This is analogous to the CMU Common Lisp ceiling function. :negative-infinity This mode rounds inexact results to the possible value closer to negative infinity. This is analogous to the CMU Common Lisp floor function. :zero This mode rounds inexact results to the possible value closer to zero. This is analogous to the CMU Common Lisp truncate function. WARNING: Although the rounding mode can be changed with `set-floating-point-modes', use of any value other than the default (:nearest) can cause unusual behavior, since it will affect rounding done by Common Lisp system code as well as rounding in user code. In particular, the unary `round' function will stop doing round-to-nearest on floats, and instead do the selected form of rounding. File: cmu-user.info Node: Accessing the Floating Point Modes, Prev: Floating Point Rounding Mode, Up: Floats Accessing the Floating Point Modes .................................. These functions can be used to modify or read the floating point modes: -- Function: set-floating-point-modes &keys :traps :rounding-mode :fast-mode :accrued-exceptions :current-exceptions -- Function: get-floating-point-modes The keyword arguments to `set-floating-point-modes' set various modes controlling how floating point arithmetic is done: :traps A list of the exception conditions that should cause traps. Possible exceptions are :underflow, :overflow, :inexact, :invalid and :divide-by-zero. Initially all traps except :inexact are enabled. *Note Floating Point Exceptions::. :rounding-mode The rounding mode to use when the result is not exact. Possible values are :nearest, :positive-infinity, :negative-infinity and :zero. Initially, the rounding mode is :nearest. See the warning in section *Note Floating Point Rounding Mode:: about use of other rounding modes. :current-exceptions, :accrued-exceptions Lists of exception keywords used to set the exception flags. The CURRENT-EXCEPTIONS are the exceptions for the previous operation, so setting it is not very useful. The ACCRUED-EXCEPTIONS are a cumulative record of the exceptions that occurred since the last time these flags were cleared. Specifying `()' will clear any accrued exceptions. :fast-mode Set the hardware's "fast mode" flag, if any. When set, IEEE conformance or debuggability may be impaired. Some machines may not have this feature, in which case the value is always false. No currently supported machines have a fast mode. If a keyword argument is not supplied, then the associated state is not changed. `get-floating-point-modes' returns a list representing the state of the floating point modes. The list is in the same format as the keyword arguments to `set-floating-point-modes', so `apply' could be used with `set-floating-point-modes' to restore the modes in effect at the time of the call to `get-floating-point-modes'. File: cmu-user.info Node: Characters, Prev: Floats, Up: Data Types, Next: Array Initialization Characters ---------- CMU Common Lisp implements characters according to Common Lisp: the Language II. The main difference from the first version is that character bits and font have been eliminated, and the names of the types have been changed. base-character is the new equivalent of the old string-char. In this implementation, all characters are base characters (there are no extended characters.) Character codes range between `0' and `255', using the ASCII encoding. File: cmu-user.info Node: Array Initialization, Prev: Characters, Up: Data Types Array Initialization -------------------- If no `:initial-value' is specified, arrays are initialized to zero. File: cmu-user.info Node: Default Interrupts for Lisp, Prev: Data Types, Up: Design Choices and Extensions, Next: Packages Default Interrupts for Lisp =========================== CMU Common Lisp has several interrupt handlers defined when it starts up, as follows: `SIGINT' (^c) causes Lisp to enter a break loop. This puts you into the debugger which allows you to look at the current state of the computation. If you proceed from the break loop, the computation will proceed from where it was interrupted. `SIGQUIT' (^\\) causes Lisp to do a throw to the top-level. This causes the current computation to be aborted, and control returned to the top-level read-eval-print loop. `SIGTSTP' (^z) causes Lisp to suspend execution and return to the Unix shell. If control is returned to Lisp, the computation will proceed from where it was interrupted. `SIGILL', `SIGBUS', `SIGSEGV', and `SIGFPE' cause Lisp to signal an error. For keyboard interrupt signals, the standard interrupt character is in parentheses. Your `.login' may set up different interrupt characters. When a signal is generated, there may be some delay before it is processed since Lisp cannot be interrupted safely in an arbitrary place. The computation will continue until a safe point is reached and then the interrupt will be processed. ? to define your own signal handlers. File: cmu-user.info Node: Packages, Prev: Default Interrupts for Lisp, Up: Design Choices and Extensions, Next: The Editor Packages ======== When CMU Common Lisp is first started up, the default package is the `user' package. The `user' package uses the `common-lisp', `extensions', and `pcl' packages. The symbols exported from these three packages can be referenced without package qualifiers. This section describes packages which have exported interfaces that may concern users. The numerous internal packages which implement parts of the system are not described here. Package nicknames are in parenthesis after the full name. `alien', `c-call' Export the features of the Alien foreign data structure facility (?.) `pcl' This package contains PCL (Portable CommonLoops), which is a portable implementation of CLOS (the Common Lisp Object System.) This implements most (but not all) of the features in the CLOS chapter of . `debug' The `debug' package contains the command-line oriented debugger. It exports utility various functions and switches. `debug-internals' The `debug-internals' package exports the primitives used to write debuggers. ?. `extensions (ext)' The `extensions' packages exports local extensions to Common Lisp that are documented in this manual. Examples include the `save-lisp' function and time parsing. `hemlock (ed)' The `hemlock' package contains all the code to implement Hemlock commands. The `hemlock' package currently exports no symbols. `hemlock-internals (hi)' The `hemlock-internals' package contains code that implements low level primitives and exports those symbols used to write Hemlock commands. `keyword' The `keyword' package contains keywords (e.g., :start). All symbols in the `keyword' package are exported and evaluate to themselves (i.e., the value of the symbol is the symbol itself). `profile' The `profile' package exports a simple run-time profiling facility (?). `common-lisp (cl lisp)' The `common-lisp' package exports all the symbols defined by Common Lisp: the Language and only those symbols. Strictly portable Lisp code will depend only on the symbols exported from the `lisp' package. `unix', `mach' These packages export system call interfaces to generic BSD Unix and Mach (?). `system (sys)' The `system' package contains functions and information necessary for system interfacing. This package is used by the `lisp' package and exports several symbols that are necessary to interface to system code. `common-lisp-user (user cl-user)' The `common-lisp-user' package is the default package and is where a user's code and data is placed unless otherwise specified. This package exports no symbols. `xlib' The `xlib' package contains the Common Lisp X interface (CLX) to the X11 protocol. This is mostly Lisp code with a couple of functions that are defined in C to connect to the server. `wire' The `wire' package exports a remote procedure call facility (?). File: cmu-user.info Node: The Editor, Prev: Packages, Up: Design Choices and Extensions, Next: Garbage Collection The Editor ========== The `ed' function invokes the Hemlock editor which is described in Hemlock User's Manual and Hemlock Command Implementor's Manual. Most users at CMU prefer to use Hemlock's slave Common Lisp mechanism which provides an interactive buffer for the `read-eval-print' loop and editor commands for evaluating and compiling text from a buffer into the slave Common Lisp. Since the editor runs in the Common Lisp, using slaves keeps users from trashing their editor by developing in the same Common Lisp with Hemlock. File: cmu-user.info Node: Garbage Collection, Prev: The Editor, Up: Design Choices and Extensions, Next: Describe Garbage Collection ================== CMU Common Lisp uses a stop-and-copy garbage collector that compacts the items in dynamic space every time it runs. Most users cause the system to garbage collect (GC) frequently, long before space is exhausted. With 16 or 24 megabytes of memory, causing GC's more frequently on less garbage allows the system to GC without much (if any) paging. The following functions invoke the garbage collector or control whether automatic garbage collection is in effect: -- Function: gc This function runs the garbage collector. If `ext:*gc-verbose*' is non-nil, then it invokes `ext:*gc-notify-before*' before GC'ing and `ext:*gc-notify-after*' afterwards. -- Function: gc-off This function inhibits automatic garbage collection. After calling it, the system will not GC unless you call `ext:gc' or `ext:gc-on'. -- Function: gc-on This function reinstates automatic garbage collection. If the system would have GC'ed while automatic GC was inhibited, then this will call `ext:gc'. The following variables control the behavior of the garbage collector: -- Variable: *bytes-consed-between-gcs* CMU Common Lisp automatically GC's whenever the amount of memory allocated to dynamic objects exceeds the value of an internal variable. After each GC, the system sets this internal variable to the amount of dynamic space in use at that point plus the value of the variable `ext:*bytes-consed-between-gcs*'. The default value is 2000000. -- Variable: *gc-verbose* This variable controls whether `ext:gc' invokes the functions in `ext:*gc-notify-before*' and `ext:*gc-notify-after*'. If `*gc-verbose*' is nil, `ext:gc' foregoes printing any messages. The default value is `T'. -- Variable: *gc-notify-before* This variable's value is a function that should notify the user that the system is about to GC. It takes one argument, the amount of dynamic space in use before the GC measured in bytes. The default value of this variable is a function that prints a message similar to the following: [GC threshold exceeded with 2,107,124 bytes in use. Commencing GC.] -- Variable: *gc-notify-after* This variable's value is a function that should notify the user when a GC finishes. The function must take three arguments, the amount of dynamic spaced retained by the GC, the amount of dynamic space freed, and the new threshold which is the minimum amount of space in use before the next GC will occur. All values are byte quantities. The default value of this variable is a function that prints a message similar to the following: [GC completed with 25,680 bytes retained and 2,096,808 bytes freed.] [GC will next occur when at least 2,025,680 bytes are in use.] Note that a garbage collection will not happen at exactly the new threshold printed by the default `ext:*gc-notify-after*' function. The system periodically checks whether this threshold has been exceeded, and only then does a garbage collection. -- Variable: *gc-inhibit-hook* This variable's value is either a function of one argument or nil. When the system has triggered an automatic GC, if this variable is a function, then the system calls the function with the amount of dynamic space currently in use (measured in bytes). If the function returns nil, then the GC occurs; otherwise, the system inhibits automatic GC as if you had called `ext:gc-off'. The writer of this hook is responsible for knowing when automatic GC has been turned off and for calling or providing a way to call `ext:gc-on'. The default value of this variable is nil. -- Variable: *before-gc-hooks* -- Variable: *after-gc-hooks* These variables' values are lists of functions to call before or after any GC occurs. The system provides these purely for side-effect, and the functions take no arguments. File: cmu-user.info Node: Describe, Prev: Garbage Collection, Up: Design Choices and Extensions, Next: The Inspector Describe ======== In addition to the basic function described below, there are a number of switches and other things that can be used to control `describe''s behavior. -- Function: describe OBJECT &optional STREAM The `describe' function prints useful information about OBJECT on STREAM, which defaults to `*standard-output*'. For any object, `describe' will print out the type. Then it prints other information based on the type of OBJECT. The types which are presently handled are: hash-table `describe' prints the number of entries currently in the hash table and the number of buckets currently allocated. function `describe' prints a list of the function's name (if any) and its formal parameters. If the name has function documentation, then it will be printed. If the function is compiled, then the file where it is defined will be printed as well. fixnum `describe' prints whether the integer is prime or not. symbol The symbol's value, properties, and documentation are printed. If the symbol has a function definition, then the function is described. If there is anything interesting to be said about some component of the object, describe will invoke itself recursively to describe that object. The level of recursion is indicated by indenting output. -- Variable: *describe-level* The maximum level of recursive description allowed. Initially two. -- Variable: *describe-indentation* The number of spaces to indent for each level of recursive description, initially three. -- Variable: *describe-print-level* -- Variable: *describe-print-length* The values of `*print-level*' and `*print-length*' during description. Initially two and five. File: cmu-user.info Node: The Inspector, Prev: Describe, Up: Design Choices and Extensions, Next: Load The Inspector ============= CMU Common Lisp has both a graphical inspector that uses X windows and a simple terminal-based inspector. -- Function: inspect &optional OBJECT `Inspect' calls the inspector on the optional argument OBJECT. If OBJECT is unsupplied, `inspect' immediately returns false. Otherwise, the behavior of inspect depends on whether Lisp is running under X. When `inspect' is eventually exited, it returns some selected Lisp object. * Menu: * The Windowing Inspector:: * The TTY Inspector:: File: cmu-user.info Node: The Windowing Inspector, Prev: The Inspector, Up: The Inspector, Next: The TTY Inspector The Windowing Inspector ----------------------- If X is available, `inspect' creates an X window and displays OBJECT in the window. While `inspect' is running and the cursor is in the inspector's X window, mouse clicks and keyboard input have the following meaning: Left When the left mouse button is clicked over a component object, that object will be inspected in the current inspector window. Middle When the middle mouse button is clicked over a component object, `inspect' is exited returning the component as the result. All the new inspector windows are deleted. Shift Middle When the shift key is depressed and the middle mouse button is clicked over a component object, `inspect' exits and returns the component as the result. All the inspector windows are left displayed on the screen. Right When the right mouse button is clicked over a component object, that object will be inspected in a new inspector window. d, D When either d or D is typed, the current window is deleted. If there are no more windows, then `inspect' exits and returns the original OBJECT. h, H, ? When any of h, H, or ? are typed while in an inspector window, a new window with help information is displayed. m, M When either m or M is typed, a component object may be modified. The cursor changes to an arrow with an M beside it. Clicking any mouse button while the mouse is over a component will select that component as the destination for modification. If m was typed, the source object is also selected by the mouse which is indicated by an S beside the arrow in the cursor. If M was typed, the source object will be prompted for on the *query-io* stream. The source object replaces the destination object. While choosing the destination or source with the mouse, the operation can be aborted by type q or Q. q, Q When either q or Q is typed, `inspect' exits and returns the original OBJECT. All new inspector windows are deleted. p, P When either p or P is typed, `inspect' exits and returns the original OBJECT. All the inspector windows are left on the screen. r, R When either r or R is typed, the current inspector display is recomputed. This is necessary to maintain a consistent display for an object that may have changed since the display was originally computed. u, U When either u or U is typed, the object of which the current object is a component is displayed. This is the inverse operation to clicking the left mouse button over a component object. If the window is currently displaying the top level object, nothing changes. When the cursor is over a component object, the object is highlighted with a surrounding box. File: cmu-user.info Node: The TTY Inspector, Prev: The Windowing Inspector, Up: The Inspector The TTY Inspector ----------------- If X is unavailable, a terminal inspector is invoked. The TTY inspector is a crude interface to `describe' which allows objects to be traversed and maintains a history. This inspector prints information about and object and a numbered list of the components of the object. The command-line based interface is a normal `read'--`eval'--`print' loop, but an integer N descends into the N'th component of the current object, and symbols with these special names are interpreted as commands: U Move back to the enclosing object. As you descend into the components of an object, a stack of all the objects previously seen is kept. This command pops you up one level of this stack. Q, E Return the current object from `inspect'. R Recompute object display, and print again. Useful if the object may have changed. D Display again without recomputing. H, ? Show help message. File: cmu-user.info Node: Load, Prev: The Inspector, Up: Design Choices and Extensions, Next: The Reader Load ==== -- Function: load FILENAME &keys :verbose :print :if-does-not-exist :if-source-newer :contents As in standard Common Lisp, this function loads a file containing source or object code into the running Lisp. Several CMU extensions have been made to `load' to conveniently support a variety of program file organizations. FILENAME may be a wildcard pathname such as `*.lisp', in which case all matching files are loaded. If FILENAME has a `pathname-type' (or extension), then that exact file is loaded. If the file has no extension, then this tells `load' to use a heuristic to load the "right" file. The `*load-source-types*' and `*load-object-types*' variables below are used to determine the default source and object file types. If only the source or the object file exists (but not both), then that file is quietly loaded. Similarly, if both the source and object file exist, and the object file is newer than the source file, then the object file is loaded. The value of the IF-SOURCE-NEWER argument is used to determine what action to take when both the source and object files exist, but the object file is out of date: :load-object The object file is loaded even though the source file is newer. :load-source The source file is loaded instead of the older object file. :compile The source file is compiled and then the new object file is loaded. :query The user is asked a yes or no question to determine whether the source or object file is loaded. This argument defaults to the value of `ext:*load-if-source-newer*' (initially `:load-object'.) The CONTENTS argument can be used to override the heuristic (based on the file extension) that normally determines whether to load the file as a source file or an object file. If non-null, this argument must be either `:source' or `:binary', which forces loading in source and binary mode, respectively. You really shouldn't ever need to use this argument. -- Variable: *load-source-types* -- Variable: *load-object-types* These variables are lists of possible `pathname-type' values for source and object files to be passed to `load'. These variables are only used when the file passed to `load' has no type; in this case, the possible source and object types are used to default the type in order to determine the names of the source and object files. -- Variable: *load-if-source-newer* This variable determines the default value of the IF-SOURCE-NEWER argument to `load'. Its initial value is `:load-object'.